Customizing the ribbon

The project administrator can customize the ribbon interface of CADMATIC applications. Using XML code, the administrator can add new tabs, groups, and command buttons with drop-down menus to the ribbon. When the user selects a custom command from the ribbon or uses the associated hotkey, the application runs the custom script that the administrator has assigned to the given command. Hotkeys can also be added to the default commands of the ribbon. If the given command already has a default hotkey, the custom hotkey overrides the default hotkey.

These CADMATIC applications have a customizable ribbon:

  • Plant Modeller

  • Plant Modeller document editor

  • P&ID

Starting the application reads the XML code and adds the custom commands to the ribbon. The XML specifies where and how each custom command should appear:

  • On an existing tab or on a new tab.

  • In the Custom group or in a new group named by the administrator.

  • As a separate button or as one item in a drop-down menu.

  • Using the default icon or a custom icon.

The required customizations can be defined in a single file or distributed to separate files, as appropriate.

In this help topic we use Plant Modeller as the example application and show some ways in which its ribbon can be customized.

The XML format

The XML code that customizes the ribbon interface of CADMATIC applications can contain command definitions and hotkey definitions, for one or several ribbons.

This customization adds one custom command to an existing tab:

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="structuralTab">
      <CustomCommand Name="My Route Wall" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" />
    </RibbonTab>
  </Ribbon>
</RibbonSettings>

This customization creates a custom tab with one custom group and one custom command as well as replaces the default hotkey of an existing command with a custom hotkey:

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="myCustomTab1" Text="My Custom Tab" Index="0">
      <TabGroup Name="myCustomGroup1" Text="My Custom Group">
        <CustomCommand Name="My Custom Command" CommandData="C:\MyScript.mac main()" Hotkey="Shift+R" />
      </TabGroup>
    </RibbonTab>
    <CustomHotkey Target="12100" Hotkey="F2" />
  </Ribbon>
</RibbonSettings>

The XML format does not change between CADMATIC software releases, so there is no need to update your customization XML when you upgrade the software. However, if there are changes in the scripting interface and the custom scripts that you run from the ribbon stop working, then you need to update those scripts as required.

Certain characters are reserved to the XML format and therefore they are not allowed to be used inside XML data fields. If the attribute values in your XML code must contain those characters, replace the invalid character with the respective named entity, as shown below.

Reserved Characters in XML

Reserved character
(not allowed in XML data)

Named entity
(allowed in XML data)

"

&quot;

&

&amp;

'

&apos;

<

&lt;

>

&gt;

You can customize the application ribbon using the following XML elements.

Ribbon | RibbonTab | TabGroup | CustomCommand | CustomHotkey | CustomDropDown | CustomSeparator

Ribbon

The "Ribbon" XML element defines the target ribbon.

This element has a single attribute.

Attribute name

Attribute value

Comments

Name

ribbon identifier

The internal name of the ribbon to modify.

  • main – The main ribbon of the Plant Modeller application.

  • Diagram – The main ribbon of the P&ID application.

  • drawingRibbon – The ribbon of the document editor.

Ribbon elements can contain:

  • RibbonTab elements that specify whether to customize an existing tab or create a new one.

  • CustomHotkey elements that add a custom hotkey to an existing command.

RibbonTab

The "RibbonTab" XML element defines the target tab. If the tab does not exist in the specified ribbon, a new tab is created.

This element can have the following attributes.

Attribute name

Attribute value

Comments

Name

tab identifier

The internal name of the tab. The value of this attribute specifies whether the customization will modify an existing tab or create a new tab.

If the intention is to modify an existing tab, the attribute value should be one of the following.

  • Plant Modeller tab names:

    • homeTab

    • layoutTab

    • pipingTab

    • ductTab

    • cableTrayTab

    • structuralTab

    • weldTab

    • documentsTab

    • toolsTab

    • modelTab

    • spoolsTab

  • Plant Modeller document editor tab names:

    • homeTab

    • draftingTab

    • importTab

    • toolsTab

    Important: On the Drafting tab and the Import tab of the document editor, custom commands are run as DW scripts so that they can modify 2D annotations via DW script externs, using the currently selected page or view and annotation property defaults. On the other tabs they are run as Plant Modeller scripts.

  • P&ID tab names:

    • homeTab

    • insertTab

    • modifyTab

    • draftingTab

    • toolsTab

If the intention is to create a new tab, the attribute value should contain a unique name that is not yet used by any other tab in the target application, such as "myCustomTab1".

Text

tab name

(Optional) The tab name to show in the ribbon.

If not specified, the value of the Name attribute is shown.

Index

tab index

(Optional) The ordinal number of the tab (counting starts from zero).

If the order is not specified in XML or the index value is invalid, the tab is added to the end.

RibbonTab elements can contain:

  • TabGroup elements that add a group to specified tab.

  • CustomCommand elements that add a command button to the specified tab.

  • CustomDropDown elements that add a command button with a drop-down menu to the specified tab.

Example

Example 1 – Adding a custom command to an existing tab

TabGroup

The "TabGroup" XML element defines the target group. If the group does not exist on the specified tab, a new group is created.

If the target group is not defined, the commands are added to the default Custom group.

This element can have the following attributes.

Attribute name

Attribute value

Comments

Name

group identifier

The internal name of the group, such as "myCustomGroup1".

If a group by the given name already exists, Text and Index are ignored.

Text

group name

(Optional) The group name to show in the ribbon.

If not specified, the value of the Name attribute is shown.

Index

group index

(Optional) The ordinal number of the group (counting starts from zero).

If the order is not specified in XML or the index value is invalid, the group is added to the end.

Example

Example 3 – Adding a custom tab with custom groups

CustomCommand

The "CustomCommand" XML element defines the command to be added to the ribbon. The actual functionality of the command is implemented as a script whose location is defined in an attribute.

This element can have the following attributes.

Attribute name

Attribute value

Comments

Name

command name

The command name to show in the ribbon.

CommandData

path to script file

function interface to call

The path to the script file to be run. If the command is to run a specific function in that file, the function comes after the path and is separated from the path with the space character.

CommandData="C:\MyScript.mac main()"

Note that certain characters are reserved to the XML format and normally they cannot be used as part of the attribute value, as described in Reserved Characters in XML. If you must use double quotes (") in your CommandData definition, use single quotes (') instead of double quotes around the attribute value, as shown below.

CommandData='macro/ChangeObjPid.mac ChangeDMPartId("AIRDUCT")'

Index

button index

(Optional) The ordinal number of the button in the group (counting starts from zero).

If the order is not specified in XML or the index value is invalid, the button is added to the end.

Hotkey

modifier key(s) + key

(Optional) A single key or key combination for running the command from the keyboard, regardless of which tab is currently active.

Modifier keys are Shift, Ctrl, and Alt. Separator character in key combinations is + and there must be no spaces around it: "Shift+A"

For information on how to refer to various keys on the keyboard, see the "Key Enums" list at docs.microsoft.com. For example, if you want the hotkey to use the 1 (one) key, "D1" is the normal 1 key and "NumPad1" is the 1 key on the numeric keypad.

Image

path to the image file

(Optional) The icon to display in the command button.

Supported formats: ICO, PNG, JPG, GIF, BMP

If not defined, the default script icon is shown.

Example

Example 1 – Adding a custom command to an existing tab

CustomHotkey

The "CustomHotkey" XML element adds a custom hotkey to an existing command in the ribbon. If the command has a default hotkey, the custom hotkey overrides it.

Note: You cannot use this to override the hotkeys that are used in 3D digitizing and navigation.

This element can have the following attributes.

Attribute name

Attribute value

Comments

Target

identifier of target command

A number or text string that identifies the target command, such as "19300" (opens the Object properties dialog) or "Find_Search_Tool" (opens the Find Objects dialog).

Most commands in the ribbon have this identifier, but not all. You can see the hotkey identifier value of a given command in its tooltip text, as shown below.

If the identifiers are not shown, go to File > Options > User Settings > User Interface and select the user interface option Show command ids for custom hotkeys in tooltips, as described in Ribbon tooltips.

Hotkey

modifier key(s) + key

A single key or key combination for running the command from the keyboard, regardless of which tab is currently active.

Modifier keys are Shift, Ctrl, and Alt. Separator character in key combinations is + and there must be no spaces around it: "Shift+A"

For information on how to refer to various keys on the keyboard, see the "Key Enums" list at docs.microsoft.com. For example, if you want the hotkey to use the 1 (one) key, "D1" is the normal 1 key and "NumPad1" is the 1 key on the numeric keypad.

Custom hotkeys are "global" by nature—they identify the target command regardless of on which tab the command is located. Make sure the hotkey is not already in use. If you define the same hotkey for multiple commands, only one of them will use the hotkey.

The CustomHotkey elements must be inside the Ribbon element. If you put a CustomHotkey element inside a RibbonTab element, the hotkey will not work.

Example

This example code defines several custom hotkeys for commands on different tabs.

Copy 
<RibbonSettings>
    <Ribbon Name="main">
        <!-- Piping > Route Pipe -->
        <CustomHotkey Target="12100" Hotkey="F2" />
        <!-- Piping > Insert default flanges -->
        <CustomHotkey Target="12300" Hotkey="F3" />        
        <!-- Piping > Insert Standard Component -->
        <CustomHotkey Target="12500" Hotkey="F4" />        
        <!-- Ducting > Route Air Duct -->
        <CustomHotkey Target="16100" Hotkey="Shift+F2" />         
        <!-- Ducting > Insert flange set -->
        <CustomHotkey Target="16101" Hotkey="Shift+F3" />
        <!-- Ducting > Insert part into straight duct -->
        <CustomHotkey Target="16500" Hotkey="Shift+F4" />        
        <!-- Cable Tray > Route Cable Tray -->
        <CustomHotkey Target="16900" Hotkey="Alt+F2" />        
        <!-- Home > Delete a set of objects -->
        <CustomHotkey Target="18500" Hotkey="F9" />
    </Ribbon>
</RibbonSettings>

For example, it replaces the default hotkey of the Piping > Route Pipe command (Alt+P) with a custom hotkey (F2).

CustomDropDown

The "CustomDropDown" XML element allows custom commands to be arranged into drop-down menus. The command button can be configured to run a specific command or to just open the menu.

This element can have the following attributes.

Attribute name

Attribute value

Comments

Name

command name

The command name to show in the ribbon.

CommandData

path to script file

function interface to call

(Optional) Specifies how the button functions when the user clicks the button:

  • If the top-level CustomDropDown element has a CommandData attribute, clicking the command button runs the specified command.

  • If the top-level CustomDropDown element does not have a CommandData attribute, clicking the button just opens the menu.

The path to the script file to be run. If the command is to run a specific function in that file, the function comes after the path and is separated from the path with the space character.

CommandData="C:\MyScript.mac main()"

Note that certain characters are reserved to the XML format and normally they cannot be used as part of the attribute value, as described in Reserved Characters in XML. If you must use double quotes (") in your CommandData definition, use single quotes (') instead of double quotes around the attribute value, as shown below.

CommandData='macro/ChangeObjPid.mac ChangeDMPartId("AIRDUCT")'

Index

button index

(Optional) The ordinal number of the button in the group (counting starts from zero).

If the order is not specified in XML or the index value is invalid, the button is added to the end.

Hotkey

modifier key(s) + key

(Optional) A single key or key combination for running the command from the keyboard, regardless of which tab is currently active.

Modifier keys are Shift, Ctrl, and Alt. Separator character in key combinations is + and there must be no spaces around it: "Shift+A"

For information on how to refer to various keys on the keyboard, see the "Key Enums" list at docs.microsoft.com. For example, if you want the hotkey to use the 1 (one) key, "D1" is the normal 1 key and "NumPad1" is the 1 key on the numeric keypad.

Image

image path

(Optional) The icon to display in the command button.

Supported formats: ICO, PNG, JPG, GIF, BMP

If not defined, the default script icon is shown.

CustomDropDown elements can contain:

  • CustomCommand elements that add a command to the drop-down menu.

  • CustomSeparator elements that add a separator line between two drop-down menu items.

Example

Example 2 – Adding custom commands to a drop-down menu

CustomSeparator

The "CustomSeparator" element adds a horizontal separator line to the designated position in the drop-down menu.

This element has no attributes.

Example

<CustomSeparator />

XML code examples

Your software installation contains a script source file that you can use to test different kinds of Plant Modeller ribbon customizations:

  • %PMS_HOME%\pm\macro\Examples\MyRouteWallTool.mac

Open the script source file with a text editor and read the implementation instructions in the file. The file contains the customization code examples that are shown below, and it also contains the actual script code that is run when you test the example commands that you have added to the ribbon.

Example 1 – Adding a custom command to an existing tab

This code example adds a My Route Wall command to the Structural tab of Plant Modeller. The command uses Shift+R as the hotkey.

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="structuralTab">
      <CustomCommand Name="My Route Wall" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" />
    </RibbonTab>
  </Ribbon>
</RibbonSettings>

When the user runs the command by clicking the button or using the hotkey, first the application compiles the script C:\MyCustomScripts\MyRouteWallTool.mac and then runs the entry function "main". An alternative approach would be to precompile the *.mac file to a binary script file (*.bs) and define the command like this:

CommandData="C:\MyCustomScripts\MyRouteWallTool.bs main()"

If the function call contains double quotes (") you can put the CommandData definition inside single quotes ('), and vice versa, or you can replace the double quotes with &quot; in the XML. For more information on how to replace characters that are invalid in XML data, see The XML format.

Example 2 – Adding custom commands to a drop-down menu

This code example adds a My Wall Routing Commands button to the Structural tab of Plant Modeller. The button has a drop-down menu with the commands Route, Edit and Properties, and there is a separator line before the last menu item. Clicking the button runs the Route command.

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="structuralTab">
      <CustomDropDown Name="My Wall Routing Commands" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" >
        <CustomCommand Name="Route" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" />
        <CustomCommand Name="Edit" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac edit_it()" Hotkey="Alt+R" Image="C:\MyCustomScripts\MyEditWall.ico" />
        <CustomSeparator />
        <CustomCommand Name="Properties" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac show_properties()" Hotkey="Ctrl+R" />
      </CustomDropDown>
    </RibbonTab>
  </Ribbon>
</RibbonSettings>

Example 3 – Adding a custom tab with custom groups

This code example adds a custom tab called My Wall Tools as the third tab (Index = 2) of the Plant Modeller ribbon. The tab contains a custom group Wall that consists of the commands Route and Edit and a custom group Info that consists of the command Properties.

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="mywalltoolsTab" Text="My Wall Tools" Index="2">
      <TabGroup Name="Mywalltools" Text="Wall">
        <CustomCommand Name="Route" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" />
        <CustomCommand Name="Edit" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac edit_it()" Hotkey="Alt+R" Image="C:\MyCustomScripts\MyEditWall.ico" />
      </TabGroup>
      <TabGroup Name="Mywallinfo" Text="Info">
        <CustomCommand Name="Properties" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac show_properties()" Hotkey="Ctrl+R" />
      </TabGroup>
    </RibbonTab>
  </Ribbon>
</RibbonSettings>

Example 4 – Adding a custom group to an existing tab

This code example adds a custom group called Wall as the third group (Index = 2) of the Structural tab of Plant Modeller. The group consists of the commands Route, Edit and Properties.

Copy 
<RibbonSettings>
  <Ribbon Name="main">
    <RibbonTab Name="structuralTab">
      <TabGroup Name="Mywalltools" Text="Wall" Index="2">
        <CustomCommand Name="Route" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac main()" Hotkey="Shift+R" Image="C:\MyCustomScripts\MyRouteWall.ico" />
        <CustomCommand Name="Edit" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac edit_it()" Hotkey="Alt+R" Image="C:\MyCustomScripts\MyEditWall.ico" />
        <CustomCommand Name="Properties" CommandData="C:\MyCustomScripts\MyRouteWallTool.mac show_properties()" Hotkey="Ctrl+R" />
      </TabGroup>
    </RibbonTab>
  </Ribbon>
</RibbonSettings>

Choosing a location for the XML

There are a number of alternative places where the XML code that customizes the ribbon interface of the application can be stored. Choose a location that fits your needs—the XML schema is always the same, wherever you store the code.

Option 1 – COS Library Database

You can store the XML content in a COS object of type "Custom UI" in the library database.

Select this option if all the users in any of your projects, on all replica sites, should use the customization.

You must approve the customization for use in the projects.

Starting the application copies the customization to the following directory:

  • %PMS_PROJROOT%/%PMS_PROJNAME%/Site/common/custom_ui

Option 2 – COS Project Database

You can store the XML content in a COS object of type "Custom UI" in the project database.

Select this option if all the users in the given project, on all its replica sites, should use the customization.

Starting the application copies the customization to the following directory:

  • %PMS_PROJROOT%/%PMS_PROJNAME%/Site/common/custom_ui.

Option 3 – Site Directory

You can store the XML content in a file that you save in the following directory:

  • %PMS_PROJROOT%/%PMS_PROJNAME%/Site/local/custom_ui/

Select this option if all the users on this site of the project should use the customization.

You can also use this option to test a customization locally before you store it in COS.

Option 4 – Installation Directory

You can store the XML content in a file named ui.xml that you save in the following directory (or in one of its subdirectories):

  • %PMS_HOME%\custom\

Important: Although this option has been used in the past for CADMATIC customer implementations, we no longer recommend it because every version upgrade—even a minor version upgrade—will delete the directory structure and restore its default contents, possibly causing customization files to be lost.

Creating a new customization

Using the CADMATIC desktop (note that you cannot use Plant Modeller for this), you can create a new customization in the library or the project database, as described below.

Note: We recommend that you test your new customizations in your private environment before storing them in the common library or project database.

Prerequisites

Do the following:

  1. In the CADMATIC desktop, select Object > Library and Project Databases. The Project Environment dialog opens.

  2. Browse to [library or project] > Resources > Custom UI.

  3. Select New > Custom UI. The Edit Object Attributes dialog opens.

  4. Enter a suitable name (description) for the "Custom UI" object and click OK.

  5. Right-click the new "Custom UI" object and select Edit. The object opens in the default text editor.

  6. In the text editor, write the required XML code (see The XML format if needed), and save the file.

  7. Check in the "Custom UI" object.

  8. If you created the customization in the library database, approve the "Custom UI" object for use in the project.

  9. Start the target application and see that the customization works as intended.